# 第 8 章 插件系统：五个市场、三层作用域与供应链

专家是插件，但插件远不止专家。第 5 章的系统提示词模板装在「内置市场」里，文档处理能力来自「官方市场」，团队协作件来自「Teams 市场」——WorkBuddy 的一半能力是以插件形式存在的。这一章把插件系统整体摊开：市场怎么分发、安装怎么登记、插件能往你的对话里塞什么。

这一章的最后一个词是「供应链」。插件机制给了第三方进入你请求上下文的通道，能力与风险同源。读完本章，你应能看懂插件目录的三件套登记结构，说出五个市场各自的定位，理解插件的四类注入物，并建立装插件前的评估习惯。

## 8.1 三件套：登记、注册表、开关

WorkBuddy 的插件管理用三个文件协作，全在 `~/.workbuddy/plugins/` 下。

**安装清单 `installed_plugins.json`**：记录装了什么。每个条目的键名是「插件名@市场名」，值里有安装路径、版本、安装时间，还有一个值得注意的字段——`scope: "user"`。作用域字段的存在暗示插件可以装在不同层级（官方工程复盘明确说了三层：团队、项目、个人），用户级只是其中一层。

**市场注册表 `known_marketplaces.json`**：记录从哪装。本机注册的市场信息里能看到完整分发链路：市场以压缩包形式从官方下载域名分发，支持自动更新，包内一份清单列出市场里的全部插件及其技能路径。

**总开关 `settings.json` 的 `enabledPlugins`**：装了不等于启用。每个插件一行布尔值，你在界面上点开的每个开关，落盘就是这行 true 或 false。

三件套的分工是干净的注册-配置分离：市场注册表管「货源」，安装清单管「库存」，设置文件管「通电」。排查插件问题时按这个顺序查：先看开关，再看安装，最后看市场。

## 8.2 五个市场：一次生态考古

本机 5.3.13 实测有五个市场目录，名字本身就是一份生态地图：

| 市场 | 定位 | 本机样本 |
|-|-|-|
| codebuddy-plugins-official | 开发者官方插件市场 | 浏览器自动化、文档处理、LSP 语言服务、敏捷工作流 |
| cb_teams_marketplace | 团队协作市场 | 内部通讯、文档技能、财务数据 |
| workbuddy-builtin | WorkBuddy 内置 | 提示词模板、腾讯文档套件、支付、记忆片段 |
| experts | 专家市场 | 资讯专家、视频生成专家 |
| nowledge-community | 社区市场 | 知识管理类 |

注意前两个市场的名字：CodeBuddy 是腾讯的开发者工具品牌。WorkBuddy 的插件格式（`.codebuddy-plugin` 清单目录）、技能市场格式（`.codebuddy-skill`）、分发域名全部复用 CodeBuddy 体系——**WorkBuddy 的扩展生态不是从零建的，是站在开发者工具生态上长出来的**。这件事的完整含义在第 13 章展开，这里先记住它解释了一个实际好处：为 CodeBuddy 写的插件，理论上能直接在 WorkBuddy 里安装运行。

![五个插件市场与同源关系](/workbuddy-harness/fig-10.png)

*图 8-1：五个插件市场与同源关系。*

## 8.3 插件能注入什么：四类内容

一个插件包可以向你的 WorkBuddy 注入四类东西，侵入度递增。

**第一类：技能（skills）。** 一套「怎么做某事」的方法论文档，模型按需读取。最温和——技能不进系统提示词，只在被调用时进入上下文。

**第二类：智能体（agents）。** 人设提示词，专家就是这类内容的典型。注入时替代或叠加默认人格（第 6、7 章的机制）。

**第三类：规则（rules）。** 常驻约束。本机专家样本的规则文件带着这样的元数据：`alwaysApply: true`。翻译过来：**只要这个插件启用，这条规则进入你每一次对话**，不问你当时在干什么。插件规则还支持按场景注入——样本里能看到以系统提醒形式包裹的「用户已选择视频生成场景」声明，规则与场景绑定。

**第四类：MCP 与工具（mcps）。** 直接连到外部服务的通道，第 11 章专讲。

四类内容里，规则是评估插件时最要紧的一环。技能是「书架上的书」，规则是「贴在显示器上的便条」——后者永远在场。装一个带 `alwaysApply` 规则的插件，等于接受它对你全部对话的持续影响。

![插件五级注入能力的侵入度梯度](/workbuddy-harness/fig-11.png)

*图 8-2：插件五级注入能力的侵入度梯度。*

## 8.4 运行数据与生命周期

插件不只有代码，还有状态。`plugins/data/` 下每个插件一个运行数据目录（本机可见文档套件与支付插件的数据目录）；`plugins/cache/` 存各市场的已安装版本，市场更新走「下载新版到缓存、改安装指针」的路径。生命周期上，更新日志显示插件机制本身也在快速演进——5.3.5 版本条目「WorkBuddy 扩展插件 Hook」：插件可以在指定事件（如删除文件、发送消息、支付）上挂确认拦截。Hook 是四类注入之外的第五种能力：**不只影响说什么，还能影响什么被允许发生**。

## 8.5 登记条目长什么样

把安装清单的真实条目结构展开（本机样本，字段名为实测）：

```
"playwright-cli@codebuddy-plugins-official": [
  {
    "scope": "user",
    "installPath": "~/.workbuddy/plugins/cache/codebuddy-plugins-official/playwright-cli/0.1.0",
    "version": "0.1.0",
    "installedAt": "2026-08-11T02:26:23.897Z",
    "lastUpdated": "2026-08-15T05:42:41.853Z"
  }
]
```

三个阅读点。键名里的 `@` 后缀是市场标识——同一个插件名可以同时存在于多个市场，装了哪个由键名决定。值是数组，为多版本、多作用域的并存留了结构空间（本机全部是单元素）。`lastUpdated` 与 `installedAt` 分开记，配合市场的 `autoUpdate` 标志，能看出这个插件是「装完就没动」还是「天天在更新」——排查行为突变时，先看这个时间戳。

上一节的钩子（Hook）机制在这里再强调一句安全面：恶意插件的 Hook 可以把高风险操作伪装成低风险。**评估插件时，有 Hook 的要看它拦什么、放什么**。

## 8.6 供应链视角：三问一习惯

插件系统本质是一条软件供应链：市场（货源）→ 清单（目录）→ 注入（交付）。供应链的安全逻辑在这里全部适用。

评估任何插件，三问：作者是谁、可不可追溯？注入物是什么——四类内容各有哪些，`alwaysApply` 的规则写了什么？能力边界在哪——要密钥吗、连外部服务吗、装 Hook 吗？

一个习惯：装完插件，翻一眼它落到你磁盘上的实际文件（`plugins/cache/` 对应目录）。清单声称的与文件实际的是否一致，是供应链诚信的基本检查。这不是偏执——第 12 章会讲到，本地配置里明文躺着的通道令牌和模型密钥意味着什么。

## 8.7 边界

本章边界：市场与登记结构为 5.3.13 本机实测；「三层作用域」来自官方工程复盘的自述，本机只观测到用户层实例，团队层与项目层的实际形态未取得样本；插件是否有签名校验机制未观测到证据，标注为未知——不声称有，也不声称没有。生态兼容性（CodeBuddy 插件直接可用）为格式同源推断，逐插件可用性需实测。

下一章讲插件四类注入物里最普及的两类：技能与规则文件——普通用户最可能亲手写的东西。